Quarto for the curious


Tom Mock, RStudio PBC

 rstd.io/quarto-curious

2022-07-27

We don’t talk about Quarto

We don’t talk about Quarto

We don’t talk about Quarto

A tweet by Alison Hill revealing her blogpost on Quarto. Over the weekend, I wrote up my notes about using and teaching Quarto, based on my experiences  working with the development team for over a year. I think (hope?) it is safe to talk about it now

We don’t talk about Quarto

A tweet by Kelly Bodwin revealing her excitement about Quarto. Did I stay up until 6am before the first night of class converting all my R Markdown materials to @quarto_dev? Yes, yes I did. Do I regret it? No, I do not. It's pretty rad my dudes.

We don’t talk about Quarto

We don’t talk about Quarto

Others had more questions…

What is a “Quarto”?

What is a “Quarto”?1

Ok, but what IS Quarto®?

Ok, but what IS Quarto®?

Quarto® is an open-source scientific and technical publishing system built on Pandoc

Pandoc is a “swiss army knife” for converting simple documents into other formats

Quarto extends Pandoc with heavy use of pre-processing with Lua filters

function Strong(elem)
  return pandoc.SmallCaps(elem.c)
end

and provides a native publishing workflow

quarto publish document.qmd     

How do I make a cocktail?

Image: Kobby Mendez

Crafting a cocktail

diagram of converting liquor, citrus, sugar into delicious cocktails

“Crafting” process for literate programming

“Crafting” process for literate programming

“Crafting” process for literate programming

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

diagram of converting a Jupyter notebook via pandoc into markdown and then into output formats

So what is a .qmd?

A Quarto document i.e. a .qmd is a plain text file, like a .rmd, that can be rendered to many different formats

  • Metadata (YAML)
format: html
engine: knitr
engine: jupyter #< for native Python/Julia without requiring R
  • Code
```{r cars}
#| eval: false
mtcars |> 
  dplyr::group_by(cyl) |> 
  dplyr::summarize(mean = mean(mpg), .groups = "drop")
```
  • Text
# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

So what is Quarto?

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into reports, books, websites, presentations and more!

thomasmock$ quarto --help
  Usage:   quarto
  Version: 1.0.0

  Options:
    -h, --help     - Show this help.                            
    -V, --version  - Show the version number for this program.  

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    create-project  [dir]               - Create a project for rendering multiple documents          
    convert         <input>             - Convert documents to alternate representations.            
    pandoc          [args...]           - Run the version of Pandoc embedded within Quarto.          
    run             [script] [args...]  - Run a TypeScript, R, Python, or Lua script.                
    install         <type> [target]     - Installs an extension or global dependency.                
    publish         [provider] [path]   - Publish a document or project. Available providers include:
    check           [target]            - Verify correct functioning of Quarto installation.         
    help            [command]           - Show this help or the help of a sub-command.               

So what is Quarto?



Quarto is the next-generation of RMarkdown.

For everyone.

Patrick

One install, batteries included

One install, “Batteries included”

  • Quarto comes pre-installed with RStudio v2022.07.0 and beyond! Any language, same syntax and approach
Feature R Markdown Quarto
Basic Formats
Beamer
PowerPoint
HTML Slides
Advanced Layout

Many Quarto formats

Feature R Markdown Quarto
Cross References
Websites & Blogs
Books
Interactivity Shiny Documents Quarto Interactive Documents
Paged HTML pagedown Summer 2022
Journal Articles rticles Summer 2022
Dashboards flexdashboard Fall 2022

Figure Layout

```{r}
#| label: fig-penguins
#| fig-cap: Palmer Penguins layout
#| fig-subcap: 
#|   - "Penguin appearance by species"
#|   - "Bill length vs Bill Depth"
#|   - "Distribution of flipper length"
#| layout: "[[1], [1,1]]"
#| column: page

knitr::include_graphics("images/lter_penguins.png")
bill_len_dep
flipper_hist
```

Interactivity

  • Quarto supports {htmlwidgets} and {shiny} in R or Jupyter Widgets for Python. Quarto also includes native support for Observable JS, a set of enhancements to vanilla JavaScript created by Mike Bostock (also the author of D3)

Next-Gen RMarkdown, unification

We learned from 10 years of literate programming with knitr + rmarkdown - Quarto is the continuation and unification of the best parts of RMarkdown via knitr.

RMarkdown and knitr are not going away, we’re still supporting it!

diagram of converting a Quarto document via knitr/pandoc into markdown and then into output formats

Next-Gen RMarkdown, extended for everyone

I feel as if R Markdown’s birth certificate had a letter “R” stamped on it, and Jupyter had a “Python” stamp - Yihui Xie (author of knitr) 1

The main technical difference between Quarto and R Markdown is that Quarto makes heavy use of Pandoc’s Lua filters. - Yihui Xie 2

We are meeting Julia/Python users in their native language

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

Collaboration between multi-lingual teams

Edit: Replaced mispelling of “tookis” with “toolkit”

Comfort of your own workspace

Photo by zero take

roam in color

Comfort of your own workspace

A screenshot of a Quarto document rendered inside RStudio

A screenshot of a Quarto document rendered inside JupyterLab

A screenshot of a Quarto document rendered inside VSCode

What to do with my existing .Rmd?

RMarkdown (and knitr) is not going away!

For some of you - nothing changes! Keep using RMarkdown and Jupyter.

However, most existing .rmd can be rendered as-is via Quarto or with some light editing. Quarto comes out of the box with better accessibility, better defaults, more options, and a more consistent syntax.

quarto render my-favorite.rmd --to html

What to do with my existing .ipynb?

You can keep using them!


Since Jupyter notebooks can either be treated as a linear document to be re-executed OR as JSON with stored computation, there are additional options like: --execute

quarto render my-favorite.ipynb --to html --execute


Quarto can help convert back and forth between plain text .qmd and .ipynb:

quarto convert --help

Usage:   quarto convert <input>

Description:

    Convert documents to alternate representations.

  Convert notebook to markdown:                  quarto convert mydocument.ipynb                   
  Convert markdown to notebook:                  quarto convert mydocument.qmd                     
  Convert notebook to markdown, writing to file: quarto convert mydocument.ipynb --output mydoc.qmd

Extending Quarto with extensions

Shortcodes

  • Replace inline “short codes” with output.
{{< fa thumbs-up >}} 


Filters

  • Affect rendering of specific items

Formats

  • Add entirely custom new formats
---
title: "Cool Company 2022 Presentation"
format: coolco-revealjs
---

Quarto Publish

quarto publish --help

  Usage:   quarto publish [provider] [path]
  Version: 1.0.0                          
                                           
  Description:
    Publish a document or project. Available providers include:
                                                               
     - Quarto Pub (quarto-pub)                                 
     - GitHub Pages (gh-pages)                                 
     - RStudio Connect (connect)                               
     - Netlify (netlify)                                       

What about for Data Science at Work?

  • Quarto can be used in the latest version (2022.07.0) of RStudio Team today!

Cocktails vs Mixed Drinks

Quarto, crafted with love and care

Development of Quarto is sponsored by RStudio, PBC. The same core team works on both Quarto and R Markdown:

Here is the full contributors list. Quarto is open source and we welcome contributions in our github repository as well! https://github.com/quarto-dev/quarto-cli.

Quarto

  • Batteries included, shared syntax across output types and languages
  • Choose your own editor and your preferred data science language
  • RMarkdown still maintained, but majority of new features built into Quarto

Follow @quarto_pub or me @thomas_mock on Twitter to stay up to date!